<!DOCTYPE html 
     PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>GMLAS - Geography Markup Language (GML) driven by application schemas</title>
</head>

<body>

<h1>GMLAS - Geography Markup Language (GML) driven by application schemas</h1>

<p>Available in GDAL &gt;= 2.2</p>

<p>This driver can read and write XML files of arbitrary structure, included those
containing so called Complex Features, provided that they are accompanied by
one or several XML schemas that describe the structure of their
content. While this driver is generic to any XML schema, the main target is to
be able to read and write documents referencing directly or indirectly to the
GML namespace.</p>

<p>The driver requires Xerces-C &gt;= 3.1.</p>

<p>The driver can deal with files of arbitrary size with a very modest RAM usage,
due to its working in streaming mode.</p>

<h2>Opening syntax</h2>

<p>The connection string is GMLAS:/path/to/the.gml. Note the GMLAS: prefix.
If this prefix it is omitted, then the GML driver is likely to be used.</p>

<p>It is also possible to only used "GMLAS:" as the connection string, but
in that case the schemas must be explicitly provided with the XSD open option.</p>


<h2>Mapping of XML structure to OGR layers and fields</h2>

<p>The driver scans the XML schemas referenced by the XML/GML to build the OGR
layers and fields. It is strictly required that the schemas, directly or indirectly
used, are fully valid. The content of the XML/GML file itself is marginally used,
mostly to determine the SRS of geometry columns.</p>

<p>XML elements declared at the top level of a schema will generally be exposed
as OGR layers. Their attributes and sub-elements of simple XML types (string,
integer, real, ...) will be exposed as OGR fields. For sub-elements of complex
type, different cases can happen. If the cardinality of the sub-element is
at most one and it is not referenced by other elements, then it is "flattened"
into its enclosing element. Otherwise it will be exposed as a OGR layer, with
either a link to its "parent" layer if the sub-element is specific to its
parent element, or through a junction table if the sub-element is shared by
several parents.</p>

<p>By default the driver is robust to documents non strictly conforming to
the schemas. Unexpected content in the document will be silently ignored, as
well as content required by the schema and absent from the document.</p>

<p>Consult the <a href="drv_gmlas_mapping_examples.html">GMLAS mapping examples</a>
page for more details.</p>

<p>By default in the configuration, swe:DataRecord and swe:DataArray elements
from the Sensor Web Enablement (SWE) Common Data Model namespace will receive
a special processing, so they are mapped more naturally to OGR concepts. The
swe:field elements will be mapped as OGR fields, and the swe:values element of
a swe:DataArray will be parsed into OGR features in a dedicated layer for each
swe:DataArray. Note that those conveniency exposure is for read-only purpose.
When using the write side of the driver, only the content of the general
mapping mechanisms will be used.</p>

<h2>Metadata layers</h2>

<p>Three special layers "_ogr_fields_metadata", "_ogr_layers_metadata",
"_ogr_layer_relationships" and "_ogr_other_metadata" add extra information to
the basic ones you can get from the OGR data model on OGR layers and fields.</p>

<p>Those layers are exposed if the EXPOSE_METADATA_LAYERS open option is set
to YES (or if enabled in the configuration). They can also be individually
retrieved by specifying their name in calls to GetLayerByName(), or on
as layer names with the ogrinfo and ogr2ogr utility.</p>

<p>Consult the <a href="drv_gmlas_metadata_layers.html">GMLAS metadata layers</a>
page for more details.</p>

<h2>Configuration file</h2>

<p>A default configuration file <a href="http://svn.osgeo.org/gdal/trunk/gdal/data/gmlasconf.xml">
gmlasconf.xml</a> file is provided in the data directory of the GDAL installation.
Its structure and content is documented in <a href="http://svn.osgeo.org/gdal/trunk/gdal/data/gmlasconf.xsd">
gmlasconf.xsd</a> schema.</p>
<p>This configuration file enables the user to modify the following settings:
</p>
<ul>
<li>whether remote schemas should be downloaded. Enabled by default.</li>
<li>whether the local cache of schemas is enabled. Enabled by default.</li>
<li>the path of the local cache. By default, $HOME/.gdal/gmlas_xsd_cache</li>
<li>whether validation of the document against the schemas should be enabled.
Disabled by default.</li>
<li>whether validation error should cause dataset opening to fail.
Disabled by default.</li>
<li>whether the metadata layers should be exposed by default. Disabled by default.</li>
<li>whether a 'ogr_pkid' field should always be generated. Disabled by default.
Turning that on can be useful on layers that have a ID attribute whose uniqueness
is not guaranteed among various documents. Which could cause issues when appending several
documents into a target database table.</li>
<li>whether layers and fields that are not used in the XML document should be
removed. Disable by default.</li>
<li>whether OGR array data types can be used. Enabled by default.</li>
<li>whether the XML definition of the GML geometry should be reported as a
OGR string field. Disabled by default.</li>
<li>whether only XML elements that derive from gml:_Feature or gml:AbstractFeature
should be considered in the initial pass of the schema building, when at least
one element in the schemas derive from them. Enabled by default.</li>
<li>several rules to configure if and how xlink:href should be resolved.</li>
<li>a definition of XPaths of elements and attributes that must be ignored, so
as to lighten the number of OGR layers and fields.</li>
</ul>

<p>This file can be adapted and modified versions can be provided to the driver
with the CONFIG_FILE open option. None of the elements of the configuration file
are required. When they are absent, the default value indicated in the schema
documentation is used.</p>
<p>Configuration can also be provided through other open options. Note that
some open options have identical names to settings present in the configuration
file. When such open option is provided, then its value will override the one
of the configuration file (either the default one, or the one provided through
the CONFIG_FILE open option).</p>

<h2>Geometry support</h2>

<p>XML schemas only indicate the geometry type but do not constraint the
spatial reference systems (SRS), so it is theoretically possible to have object
instances of the same class having different SRS for the same geometry field.
This is not practical to deal with, so when geometry fields are detected, an
initial scan of the document is done to find the first geometry of each geometry
field that has an explicit srsName set. This one will be used for the whole
geometry field. In case other geometries of the same field would have different
SRS, they will be reprojected.</p>

<p>By default, only the OGR geometry built from the GML geometry is exposed in
the OGR feature. It is possible to change the IncludeGeometryXML setting of the
configuration file to true so as to expose a OGR string field with the XML
definition of the GML geometry.</p>

<h2>Performance issues with large multi-layer GML files.</h2>

<p>Traditionnaly to read a OGR datasource, one iterate over layers with
GDALDataset::GetLayer(), and for each layer one iterate over features with
OGRLayer::GetNextFeature(). While this approach still works for the GMLAS driver,
it may result in very poor performance on big documents or documents using
complex schemas that are translated in many OGR layers.</p>

<p>It is thus recommended to use GDALDataset::GetNextFeature() to iterate over
features as soon as they appear in the .gml/.xml file. This may return features
from non-sequential layers, when the features include nested elements.</p>

<h2>Open options</h2>

<ul>
<li> <b>XSD</b>=filename(s): to specify an explicit XSD application schema to use
(or a list of filenames, provided they are comma separated). "http://"
or "https://" URLs can be used. This option is not required when the XML/GML
document has a schemaLocation attribute with valid links in its root element.</li>
<li> <b>CONFIG_FILE</b>=filename or inline XML definition: filename of a
XML configuration file conforming to the <a href="http://svn.osgeo.org/gdal/trunk/gdal/data/gmlasconf.xsd">
gmlasconf.xsd</a> schema. It is also possible to provide the XML content directly
inlined provided that the very first characters are &lt;Configuration.</li>
<li> <b>EXPOSE_METADATA_LAYERS</b>=YES/NO: whether the metadata layers
"_ogr_fields_metadata", "_ogr_layers_metadata", "_ogr_layer_relationships" and
"ogr_other_metadata" should be reported by default. Default is NO.</li>
<li> <b>VALIDATE</b>=YES/NO: whether the document should be validated against
the schemas. Validation is done at dataset opening. Default is NO.</li>
<li> <b>FAIL_IF_VALIDATION_ERROR</b>=YES/NO: Whether a validation error should
cause dataset opening to fail. (only used if VALIDATE=YES) Default is NO.</li>
<li> <b>REFRESH_CACHE</b>=YES/NO: Whether remote schemas and documents pointed
by xlink:href links should be downloaded
from the server even if already present in the local cache. If the cache is
enabled, it will be refreshed with the newly downloaded resources. Default is NO.</li>
<li> <b>SWAP_COORDINATES</b>=AUTO/YES/NO: Whether the order of the x/y or long/lat
coordinates should be swapped. In AUTO mode, the driver will determine if swapping
must be done from the srsName. If the srsName is urn:ogc:def:crs:EPSG::XXXX and
that the order of coordinates in the EPSG database for this SRS is lat,long or
northing,easting, then the driver will swap them to the GIS friendly order
(long,lat or easting,northing). For other forms of SRS (such as EPSG:XXXX), GIS
friendly order is assumed and thus no swapping is done. When SWAP_COORDINATES
is set to YES, coordinates will be always swapped regarding the order they appear
in the GML, and when it set to NO, they will be kept in the same order. The default
is AUTO.</li>
<li> <b>REMOVE_UNUSED_LAYERS</b>=YES/NO: Whether unused layers should be removed
from the reported layers. Defaults to NO</li>
<li> <b>REMOVE_UNUSED_FIELDS</b>=YES/NO: Whether unused fields should be removed
from the reported layers. Defaults to NO</li>
<li> <b>HANDLE_MULTIPLE_IMPORTS</b>=YES/NO: Whether multiple imports with the same
namespace but different schema are allowed. Defaults to NO</li>
<li> <b>SCHEMA_FULL_CHECKING</b>=YES/NO: Whether to be pedantic with XSD checking
or to be forgiving e.g. if the invalid part of the schema is not referenced in the
main document. Defaults to NO</li>
</ul>

<h2>Creation support</h2>

<p>The GMLAS driver can write XML documents in a schema-driven way by converting
a source dataset (contrary to most other drivers that have read support that
implement the CreateLayer() and CreateFeature() interfaces). The typical
workflow is to use the read side of the GMLAS driver to produce a SQLite/Spatialite/
PostGIS database, potentially modify the features imported and re-export
this database as a new XML document.</p>

<p>The driver will identify in the source dataset "top-level" layers, and in
those layers will find which features are not referenced by other top-level
layers. As the creation of the output XML is schema-driver, the schemas need to
be available. There are two possible ways:</p>
<ul>
<li>either the result of the processing of the schemas was stored as the
4 _ogr_* metadata tables in the source dataset by using the
EXPOSE_METADATA_LAYERS=YES open option when converting the source .xml),</li>
<li>or the schemas can be specified at creation time with the INPUT_XSD creation
option.</li>
</ul>

<p>By default, the driver will "wrap" the features inside a WFS 2.0
wfs:FeatureCollection / wfs:member element.
It is also possible to ask the driver to create instead a custom wrapping .xsd
file that declares the ogr_gmlas:FeatureCollection / ogr_gmlas:featureMember XML
elements.</p>

<p>Note that while the file resulting from the export should be XML valid, there
is no strong guarantee that it will validate against the additional constraints
expressed in XML schema(s). This will depend on the content of the features
(for example if converting from a GML file that is not conformant to the
schemas, the output of the driver will generally be not validating)</p>

<p>If the input layers have geometries stored as GML content in a _xml suffixed
field, then the driver will compare the OGR geometry built from that XML content
with the OGR geometry stored in the dedicated geometry field of the feature. If
both match, then the GML content stored in the _xml suffixed field will be used,
such as to preserve particularities of the initial GML content.
Otherwise GML will be exported from the OGR geometry.</p>

<p>To increase export performance on very large databases, creating attribute
indexes on the fields pointed by the 'layer_pkid_name' attribute in
'_ogr_layers_metadata' might help.</p>

<h3>ogr2ogr behaviour</h3>

<p>When using ogr2ogr / GDALVectorTranslate() to convert to XML/GML from a
source database, there are restrictions to the options that can be used.
Only the following options of ogr2ogr are supported:</p>

<ul>
<li>dataset creation options (see below)</li>
<li>layer names</li>
<li>spatial filter through -spat option.</li>
<li>attribute filter through -where option</li>
</ul>

<p>The effect of spatial and attribute filtering will only apply
on top-levels layers. Sub-features selected through joins will not be affected
by those filters.</p>

<h3>Dataset creation options</h3>

<p>The supported dataset creation options are:</p>
<ul>
<li> <b>INPUT_XSD</b>=filename(s): to specify an explicit XSD application schema to use
(or a list of filenames, provided they are comma separated). "http://"
or "https://" URLs can be used. This option is not required when the source
dataset has a _ogr_other_metadata with schemas and locations filled.</li>

<li> <b>CONFIG_FILE</b>=filename or inline XML definition: filename of a
XML configuration file conforming to the <a href="http://svn.osgeo.org/gdal/trunk/gdal/data/gmlasconf.xsd">
gmlasconf.xsd</a> schema. It is also possible to provide the XML content directly
inlined provided that the very first characters are &lt;Configuration&gt;.</li>

<li> <b>LAYERS</b>=layers. Comma separated list of layers to export as top-level
features. The special value "{SPATIAL_LAYERS}" can also be used to specify
all layers that have geometries. When LAYERS is not specified, the driver will
identify in the source dataset "top-level" layers, and in those layers will find
which features are not referenced by other top-level layers.</li>

<li> <b>SRSNAME_FORMAT</b>=SHORT/OGC_URN/OGC_URL (Only valid for GML 3 output)
Defaults to OGC_URL.
If SHORT, then srsName will be in the form AUTHORITY_NAME:AUTHORITY_CODE
If OGC_URN, then srsName will be in the form urn:ogc:def:crs:AUTHORITY_NAME::AUTHORITY_CODE
If OGC_URL, then srsName will be in the form http://www.opengis.net/def/crs/AUTHORITY_NAME/0/AUTHORITY_CODE
For OGC_URN and OGC_URL, in the case the SRS is a SRS without explicit
AXIS order,  but that the same SRS authority code imported with
ImportFromEPSGA() should be treated as lat/long or northing/easting,
then the function will take care of coordinate order swapping.</li>

<li> <b>INDENT_SIZE</b>=[0-8]. Number of spaces for each indentation level.
Default is 2.</li>

<li> <b>COMMENT</b>=string. Comment to add at top of generated XML file as a
XML comment.</li>

<li> <b>LINEFORMAT</b>=CRLF/LF. End-of-line sequence to use. Defaults to
CRLF on Windows and LF on other platforms.</li>

<li> <b>WRAPPING</b>=WFS2_FEATURECOLLECTION/GMLAS_FEATURECOLLECTION. Whether to
wrap features in a wfs:FeatureCollection or in a ogr_gmlas:FeatureCollection.
Defaults to WFS2_FEATURECOLLECTION.</li>

<li> <b>TIMESTAMP</b>=XML date time. User-specified XML dateTime value for
timestamp to use in wfs:FeatureCollection attribute. If not specified, current
date time is used. Only valid for WRAPPING=WFS2_FEATURECOLLECTION.</li>

<li> <b>WFS20_SCHEMALOCATION</b>=Path or URL to wfs.xsd. Only valid for
WRAPPING=WFS2_FEATURECOLLECTION. Default is "http://schemas.opengis.net/wfs/2.0/wfs.xsd"</li>

<li> <b>GENERATE_XSD</b>=YES/NO. Whether to generate a .xsd file that has
the structure of the wrapping ogr_gmlas:FeatureCollection / ogr_gmlas:featureMember
elements. Only valid for WRAPPING=GMLAS_FEATURECOLLECTION. Default to YES.</li>

<li> <b>OUTPUT_XSD_FILENAME</b>=string. Wrapping .xsd filename. If not specified,
same basename as output file with .xsd extension. Note that it is possible
to use this option even if GENERATE_XSD=NO, so that the wrapping .xsd appear
in the schemaLocation attribute of the .xml file. Only valid for
WRAPPING=GMLAS_FEATURECOLLECTION</li>

</ul>

<h2>Examples</h2>

<p>
Listing content of a data file:
</p>
<pre>
ogrinfo -ro GMLAS:my.gml
</pre>

<p>
Converting to PostGIS:
</p>
<pre>
ogr2ogr -f PostgreSQL PG:'host=myserver dbname=warmerda' GMLAS:my.gml -nlt CONVERT_TO_LINEAR
</pre>

<p>
Converting to Spatialite and back to GML
</p>
<pre>
ogr2ogr -f SQLite tmp.sqlite GMLAS:in.gml -dsco SPATILIATE=YES -nlt CONVERT_TO_LINEAR -oo EXPOSE_METADATA_LAYERS=YES
ogr2ogr -f GMLAS out.gml tmp.sqlite
</pre>

<h2>See Also</h2>

<ul>
<li> <a href="drv_gml.html">GML</a>: general purpose driver not requiring the presence of schemas,
but with limited support for complex features<br/></li>
<li> <a href="drv_nas.html">NAS/ALKIS</a>: specialized GML driver for cadastral data in Germany</li>
</ul>

<h2>Credits</h2>

<p>Initial implementation has been funded by the European Union's Earth observation programme
Copernicus, as part of the tasks delegated to the European Environment Agency.</p>
<p>Development of special processing of some Sensor Web Enablement (SWE)
Common Data Model swe:DataRecord and swe:DataArray constructs has been funded
by Bureau des Recherches Géologiques et Minières (BRGM).</p>

</body>
</html>
